Inside Macintosh: QuickDraw GX Objects /

Chapter 4 - Colors and Color-Related Objects / Colors and Color-Related Objects Reference

Color Profile Functions / Retrieving and Replacing Profile Information

GXGetColorProfileStructure

You can use the GXGetColorProfileStructure function to get a pointer to the profile data of a color profile object.

void *GXGetColorProfileStructure(gxColorProfile source, 
                                 long *length);

source

A reference to the color profile object whose profile data you need access to.

length

A pointer to a long value. On return, the value specifies the size in bytes of the profile data.

function result

A pointer to the profile data of the source color profile.

DESCRIPTION

The GXGetColorProfileStructure function determines the size of the profile data in a color profile object and returns a pointer to the data in the QuickDraw GX heap. You can use the pointer to examine or change the profile data without copying the data into your application's heap and back again.

Before calling this function, call GXLockColorProfile to lock the profile data in memory; after editing the profile data, call GXUnlockColorProfile to free the profile data for relocation.

The profile data returned by this function is a ColorSync color profile structure (type CMProfile).

This function is useful even if you do not intend to edit a color profile. You can use it to simply read a specific piece of color profile data, such as the white point, without having to obtain a copy of the entire profile.

SPECIAL CONSIDERATIONS

To avoid fragmenting the QuickDraw GX heap, call the GXUnlockColorProfile function as soon as possible after manipulating the profile data.

You cannot change the size of the profile data you access with this call. If your manipulations require a change in the size of the data, you must use GXGetColorProfile and GXSetColorProfile.

This function is rarely needed. In most situations you do not need to alter the
profile data of a color profile, and when you do you can use the functions GXGetColorProfile and GXSetColorProfile to make the needed changes.

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
colorProfile_is_nil

SEE ALSO

The GXLockColorProfile and GXUnlockColorProfile functions are described in the previous two sections.

The format of the profile data in a color profile object is described in the section "Profile Data" beginning on page 4-36. The ColorSync Utilities, including the CMProfile data type, are described in Inside Macintosh: Advanced Color Imaging.

To edit a copy of a color profile object's profile data, rather than directly changing the data in QuickDraw GX memory, use the GXGetColorProfile function, described on page 4-88; to assign the edited data back to the profile, use the GXSetColorProfile function, described on page 4-89.